home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / cug191 / clink.doc < prev    next >
Text File  |  1986-07-10  |  9KB  |  163 lines
  1.              Keeping a Library of C Subroutines in Source Code Form
  2.  
  3.                                Phillip L. Emerson
  4.                                    June, 1986
  5.  
  6.                 It is usual that a C program consists of quite a
  7.            number of subroutines, some quite small, and a main program
  8.            that oversees the general course of the operations.
  9.            For that reason, C programming commonly involves the use of
  10.            subroutine libraries.  There are standard libraries for
  11.            input and output, and several other kinds of operations,
  12.            that ordinarily come with the compiler when one purchases
  13.            a C programming package.  However, a programmer typically
  14.            goes beyond these libraries and develops many other small
  15.            subroutines for his own special applications.  The usual
  16.            way of implementing a library of subroutines is in
  17.            connection with a linker or linking loader and an assembler
  18.            that produces relocatable object code.
  19.                 For some purposes, it is more convenient to maintain
  20.            a library in source-code form.  CLINK is a preprocessor
  21.            program designed to link source-code subroutines from a
  22.            library file, as needed by some new program file.
  23.  
  24.                                  How CLINK Works
  25.  
  26.                 CLINK gets the name of an input program file from the
  27.            keyboard.  It then reads an index file, extracted (on some
  28.            previous run) from the library file.  It then goes through
  29.            the program file to see which, if any, of the library
  30.            subroutines are called, and at the same time putting out
  31.            the linked version of the program file with routines from
  32.            the library following the original program.  The output
  33.            file can then be compiled and/or assembled as usual with
  34.            the C programming procedure.
  35.  
  36.                 The user prepares the library file in ordinary C
  37.            source-code form, with some minor restrictions mentioned
  38.            below.  The index file is created automatically by CLINK
  39.            itself, and requires no attention from the user.
  40.            Typically, the index file is only about a tenth as long as
  41.            the library file, so CLINK tries to read the index file
  42.            first.  If the index file does not exist, then the library
  43.            file itself is used in a first pass to build the network of
  44.            interconnecting library-routine calls.  This network is
  45.            then put out into a newly created index file, to be used on
  46.            later runs.  After the first run, then, the use of the
  47.            index file reduces the processing essentially from two
  48.            passes to one pass through the library file.  For speedy
  49.            lookup of function names, CLINK uses two hash-code tables
  50.            which it creates in memory.  The first of these contains the
  51.            index-file information, and the second contains the names of
  52.            target functions called in the input program file.  After
  53.            both of these tables have been constructed (at the point
  54.            when the end of the input program file is reached), then
  55.            the second of them is expanded, using the first, to include
  56.            all ramifications of each function call.  Protection is
  57.            built in against cycling in this linkage process in cases of
  58.            recursive self calls and recursive reciprocal calls.  The
  59.            pass through the library file then begins, and any function
  60.            whose name is on the list (the second hash table) is put
  61.            out into the output file.
  62.  
  63.                 The command sequence for running CLINK is to type a
  64.            command line beginning with "CLINK" and containing at least
  65.            the name of the input program file, and optionally the
  66.            names of the library file, the index file, and the output
  67.            file.  There are some defaults, and the main ones are
  68.            USRLIB.B for the library file and LIBKEY.B for the index
  69.            file.  These defaults assume the CP/M file name structure,
  70.            so may require modifications with other operating systems.
  71.            Some of the defaults are illustrated by the example
  72.  
  73.                 >CLINK B:PROG5
  74.  
  75.            which is equivalent to
  76.  
  77.                 >CLINK B:PROG5.B B:USRLIB.B B:LIBKEY.B B:PROG5.C
  78.  
  79.            The default scheme was designed to make things convenient
  80.            on my system.  The full set of rules is rather lengthy, but
  81.            one can get the hang of it easily because CLINK pauses
  82.            after the command line is typed, and displays the four
  83.            complete file names that it has filled in.  One has a
  84.            chance then to abort before any files are opened, or
  85.            proceed.
  86.  
  87.                 If no file names at all are included on the command
  88.            line, then the procedure is somewhat different.  CLINK will
  89.            then ask for the appropriate file names at the stages when
  90.            they are needed.  There are no default substitutions, and
  91.            the names will be used, just as typed in.  This procedure
  92.            also provides for two other options.  The first is to have
  93.            CLINK scan more than one input program file for library
  94.            calls.  The second is to include or not include any subset
  95.            of the program files in the output file.  This is the
  96.            only way to handle multiple-file compilations.
  97.  
  98.                                 The Library File
  99.  
  100.                 Since CLINK selects a subset of the functions in the
  101.            library, there are some obvious constraints on the use of
  102.            declarations outside of function definitions in the library
  103.            file.  The main kind of external declaration that may not
  104.            appear at all in the library file is that in which function
  105.            types are declared separately from their definitions. For
  106.            example, in the library file,
  107.  
  108.                 int strlen() ;
  109.  
  110.            will cause trouble if it appears externally to the
  111.            definition of any function, but the type declaration along
  112.            with the definition is admissible, as in the example
  113.  
  114.                 int strlen(s) char *s {char *p; p = s;
  115.                   while(*p) p++ ; return(p-s) ; }
  116.  
  117.            This int declaration is handled properly, because CLINK looks
  118.            back and includes everything preceding a function
  119.            definition, following any preceding definition, if that
  120.            function is included.
  121.  
  122.                 As CLINK inserts library functions into the output
  123.            file,  comments, blank lines, and extra spaces are stripped
  124.            out.  Tabs are not affected, so they may be used if one
  125.            wants to keep indentations intact.  CLINK does not check
  126.            generally for syntax errors in the library file.
  127.            Therefore, it is a good idea to try compiling the library
  128.            file by itself, after any extensive changes are made in it.
  129.            Also, an old library index file should be deleted after
  130.            changes in the library file, to cause CLINK to generate a
  131.            new one.  CLINK does check for unbalanced apostrophes,
  132.            quotation marks, and comment delimiters, in the library
  133.            file.  It gives a report if it finds discrepancies.  Also,
  134.            it tries to detect discrepancies between the library file
  135.            and index file, in case an obsolete index file is used with
  136.            a new version of the library file.
  137.  
  138.                 Generally, the operation of CLINK does not depend on
  139.            the order in which the functions are defined in the library
  140.            file.  Library routines may call others in the library that
  141.            are defined earlier or later.  Routines may call themselves
  142.            recursively, and different routines may call each other
  143.            reciprocally.  One ordinarily does not have these freedoms
  144.            with the library facilities associated with the linkage of
  145.            relocatable object-code routines.  Commonly, a linker
  146.            program restrictively assumes a pure tree structure of the
  147.            intercalls among library routines.  CLINK does not.
  148.            Alphabetical order of entry of the subroutines in the CLINK
  149.            library file is as good as any other, and it can help the
  150.            programmer to find things in a listing of the file.
  151.  
  152.                 CLINK is particularly handy for implementations of C
  153.            on systems restricted in memory and disk space.  Even with
  154.            larger systems, however, it provides a more flexible and
  155.            systematic way of maintaining and using a library of
  156.            subroutines.  As one might expect, execution time of the
  157.            linkage operation is somewhat slower than with object-
  158.            code libraries.  I find source-code linking advantageous
  159.            mainly for my own user applications, where the library of
  160.            subroutines continues to change and grow rather rapidly.
  161.  
  162.  
  163.